home *** CD-ROM | disk | FTP | other *** search
/ Experimental BBS Explossion 3 / Experimental BBS Explossion III.iso / sound / sox4d.zip / ST.TXT < prev    next >
Text File  |  1992-04-16  |  8KB  |  265 lines
  1.  
  2.  
  3.  
  4. SK(1)               UNIX Programmer's Manual                SK(1)
  5.  
  6.  
  7.  
  8. NAME
  9.      st - Sound Tools - sound sample file and effects libraries.
  10.  
  11. SYNOPSIS
  12.      cc _f_i_l_e._c -o _f_i_l_e libsk.a
  13.  
  14. DESCRIPTION
  15.      _S_o_u_n_d _T_o_o_l_s is a library of sound sample file format
  16.      readers/writers and sound effects processors.
  17.  
  18.      Sound Tools includes skeleton C files to assist you in writ-
  19.      ing new formats and effects. The full skeleton driver,
  20.      skel.c, helps you write drivers for a new format which has
  21.      data structures. The simple skeleton drivers help you write
  22.      a new driver for raw (headerless) formats, or for formats
  23.      which just have a simple header followed by raw data.
  24.  
  25.      Most sound sample formats are fairly simple: they are just a
  26.      string of bytes or words and are presumed to be sampled at a
  27.      known data rate.  Most of them have a short data structure
  28.      at the beginning of the file.
  29.  
  30. INTERNALS
  31.      The Sound Tools formats and effects operate on an internal
  32.      buffer format of signed 32-bit longs.  The data processing
  33.      routines are called with buffers of these samples, and
  34.      buffer sizes which refer to the number of samples processed,
  35.      not the number of bytes.  File readers translate the input
  36.      samples to signed longs and return the number of longs read.
  37.      For example, data in linear signed byte format is left-
  38.      shifted 24 bits.
  39.  
  40.      This does cause problems in processing the data. For exam-
  41.      ple:
  42.           *obuf++ = (*ibuf++ * *ibuf++)/2;
  43.      would _n_o_t mix down left and right channels into one mono-
  44.      phonic channel, because the resulting samples would overflow
  45.      32 bits.  Instead, the ``avg'' effects must use:
  46.           *obuf++ = *ibuf++/2 * *ibuf++/2;
  47.  
  48.      Stereo data is stored with the left and right speaker data
  49.      in successive samples.  Quadraphonic data is stored in this
  50.      order: left front, right front, left rear, right rear.
  51.  
  52. FORMATS
  53.      A _f_o_r_m_a_t is responsible for translating between sound sample
  54.      files and an internal buffer.  The internal buffer is store
  55.      in signed longs with a fixed sampling rate.  The _f_o_r_m_a_t
  56.      operates from two data structures: a format structure, and a
  57.      private structure.
  58.  
  59.  
  60.  
  61.  
  62.  
  63. Printed 4/16/92                                                 1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. SK(1)               UNIX Programmer's Manual                SK(1)
  71.  
  72.  
  73.  
  74.      The format structure contains a list of control parameters
  75.      for the sample: sampling rate, data size (bytes, words,
  76.      floats, etc.), style (unsigned, signed, logarithmic), number
  77.      of sound channels.  It also contains other state informa-
  78.      tion: whether the sample file needs to be byte-swapped,
  79.      whether fseek() will work, its suffix, its file stream
  80.      pointer, its _f_o_r_m_a_t pointer, and the _p_r_i_v_a_t_e structure for
  81.      the _f_o_r_m_a_t .
  82.  
  83.      The _p_r_i_v_a_t_e area is just a preallocated data array for the
  84.      _f_o_r_m_a_t to use however it wishes. It should have a defined
  85.      data structure and cast the array to that structure. See
  86.      voc.c for the use of a private data area. Voc.c has to track
  87.      the number of samples it writes and when finishing, seek
  88.      back to the beginning of the file and write it out.  The
  89.      private area is not very large.  The ``echo'' effect has to
  90.      malloc() a much larger area for its delay line buffers.
  91.  
  92.      A _f_o_r_m_a_t has 6 routines:
  93.  
  94.      startread           Set up the format parameters, or read in
  95.                          a data header, or do what needs to be
  96.                          done.
  97.  
  98.      read                Given a buffer and a length: read up to
  99.                          that many samples, transform them into
  100.                          signed long integers, and copy them into
  101.                          the buffer.  Return the number of sam-
  102.                          ples actually read.
  103.  
  104.      stopread            Do what needs to be done.
  105.  
  106.      startwrite          Set up the format parameters, or write
  107.                          out a data header, or do what needs to
  108.                          be done.
  109.  
  110.      write               Given a buffer and a length: copy that
  111.                          many samples out of the buffer, convert
  112.                          them from signed longs to the appropri-
  113.                          ate data, and write them to the file.
  114.                          If it can't write out all the samples,
  115.                          fail.
  116.  
  117.      stopwrite           Fix up any file header, or do what needs
  118.                          to be done.
  119.  
  120. EFFECTS
  121.      An effects loop has one input and one output stream.  It has
  122.      5 routines.
  123.  
  124.      getopts             is called with a character string argu-
  125.                          ment list for the effect.
  126.  
  127.  
  128.  
  129. Printed 4/16/92                                                 2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. SK(1)               UNIX Programmer's Manual                SK(1)
  137.  
  138.  
  139.  
  140.      start               is called with the signal parameters for
  141.                          the input and output streams.
  142.  
  143.      flow                is called with input and output data
  144.                          buffers, and (by reference) the input
  145.                          and output data sizes.  It processes the
  146.                          input buffer into the output buffer, and
  147.                          sets the size variables to the numbers
  148.                          of samples actually processed.  It is
  149.                          under no obligation to fill the output
  150.                          buffer.
  151.  
  152.      drain               is called after there are no more input
  153.                          data samples.  If the effect wishes to
  154.                          generate more data samples it copies the
  155.                          generated data into a given buffer and
  156.                          returns the number of samples generated.
  157.                          If it fills the buffer, it will be
  158.                          called again, etc.  The echo effect uses
  159.                          this to fade away.
  160.  
  161.      stop                is called when there are no more input
  162.                          samples to process.  _s_t_o_p may generate
  163.                          output samples on its own.  See echo.c
  164.                          for how to do this, and see that what it
  165.                          does is absolutely bogus.
  166.  
  167. COMMENTS
  168.      Theoretically, formats can be used to manipulate several
  169.      files inside one program.  Multi-sample files, for example
  170.      the download for a sampling keyboard, can be handled cleanly
  171.      with this feature.
  172.  
  173. PORTABILITY PROBLEMS
  174.      Many computers don't supply arithmetic shifting, so do mul-
  175.      tiplies and divides instead of << and >>.  The compiler will
  176.      do the right thing if the CPU supplies arithmetic shifting.
  177.  
  178.      Do all arithmetic conversions one stage at a time.  I've had
  179.      too many problems with "obviously clean" combinations.
  180.  
  181.      In general, don't worry about "efficiency". The sox.c base
  182.      translator is disk-bound on any machine (other than a 8088
  183.      PC with an SMD disk controller). Just comment your code and
  184.      make sure it's clean and simple.  You'll find that DSP code
  185.      is extremely painful to write as it is.
  186.  
  187. BUGS
  188.      The HCOM format is not re-entrant; it can only be used once
  189.      in a program.
  190.  
  191.  
  192.  
  193.  
  194.  
  195. Printed 4/16/92                                                 3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. SK(1)               UNIX Programmer's Manual                SK(1)
  203.  
  204.  
  205.  
  206.      The program/library interface is pretty weak.  There's too
  207.      much ad-hoc information which a program is supposed to
  208.      gather up.  Sound Tools wants to be an object-oriented
  209.      dataflow architecture.
  210.  
  211.      The human ear can't really hear better than 20 bits.  With
  212.      an internal format of 16 bits, we will eventually destroy
  213.      information when used to mix CD's.  The internal format
  214.      should be 24-bit signed data.  But, with 24 bits you still
  215.      have to be careful multiplying.  Check the ``vibro'' effect
  216.      for how it handles this problem.
  217.  
  218.  
  219.  
  220.  
  221.  
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261. Printed 4/16/92                                                 4
  262.  
  263.  
  264.  
  265.